home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 1998 November / IRIX 6.5.2 Base Documentation November 1998.img / usr / share / catman / u_man / cat3 / malloc_cv.z / malloc_cv
Text File  |  1998-10-30  |  12KB  |  198 lines
  1.  
  2.  
  3.  
  4. MMMMAAAALLLLLLLLOOOOCCCC____CCCCVVVV((((3333))))                                                      MMMMAAAALLLLLLLLOOOOCCCC____CCCCVVVV((((3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      malloc, free, realloc, calloc, memalign, valloc, cvmalloc_error -
  10.      WorkShop memory allocation library
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssttttddddlllliiiibbbb....hhhh>>>>
  14.  
  15.      vvvvooooiiiidddd ****mmmmaaaalllllllloooocccc ((((ssssiiiizzzzeeee____tttt ssssiiiizzzzeeee))));;;;
  16.  
  17.      vvvvooooiiiidddd ffffrrrreeeeeeee ((((vvvvooooiiiidddd ****ppppttttrrrr))));;;;
  18.  
  19.      vvvvooooiiiidddd ****rrrreeeeaaaalllllllloooocccc ((((vvvvooooiiiidddd ****ppppttttrrrr,,,, ssssiiiizzzzeeee____tttt ssssiiiizzzzeeee))));;;;
  20.  
  21.      vvvvooooiiiidddd ****ccccaaaalllllllloooocccc ((((ssssiiiizzzzeeee____tttt nnnneeeelllleeeemmmm,,,, ssssiiiizzzzeeee____tttt eeeellllssssiiiizzzzeeee))));;;;
  22.  
  23.      vvvvooooiiiidddd ****mmmmeeeemmmmaaaalllliiiiggggnnnn ((((ssssiiiizzzzeeee____tttt aaaalllliiiiggggnnnnmmmmeeeennnntttt,,,, ssssiiiizzzzeeee____tttt ssssiiiizzzzeeee))));;;;
  24.  
  25.      vvvvooooiiiidddd ****vvvvaaaalllllllloooocccc ((((ssssiiiizzzzeeee____tttt ssssiiiizzzzeeee))));;;;
  26.  
  27.      vvvvooooiiiidddd ccccvvvvmmmmaaaalllllllloooocccc____eeeerrrrrrrroooorrrr ((((cccchhhhaaaarrrr ****mmmmeeeessssssssaaaaggggeeee))));;;;
  28.  
  29. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  30.      The WorkShop Performance Tools contain a malloc library, -lmalloc_cv,
  31.      which provides tracing and error detection around calls to the various
  32.      malloc routines.
  33.  
  34.      The library provides an intercept layer for calls to _m_a_l_l_o_c, _f_r_e_e,
  35.      _r_e_a_l_l_o_c, _m_e_m_a_l_i_g_n, and _v_a_l_l_o_c; the intercept allows tracing of all calls
  36.      with the WorkShop performance tools.
  37.  
  38.      Calls to _m_a_l_l_o_c, _f_r_e_e, and _r_e_a_l_l_o_c are passed through to whatever memory
  39.      allocation library the program is linked with.  Calls to _c_a_l_l_o_c are
  40.      actually not intercepted, but rely on the underlying calloc to call
  41.      _m_a_l_l_o_c to get the space allocated.  Calls to _m_e_m_a_l_i_g_n are implemented by
  42.      allocating a block large enough to hold the aligned area asked for by the
  43.      user, as well as a guard area that holds a flag indicating that the user
  44.      block was obtained through memalign, and the address of the larger block.
  45.      Calls to _v_a_l_l_o_c are translated into a call to getpagesize, followed by a
  46.      memalign call.
  47.  
  48.      The last function, _c_v_m_a_l_l_o_c__e_r_r_o_r is called whenever any error is
  49.      detected; a debugger trap may be placed at exit from that routine to
  50.      interactively examine malloc errors.
  51.  
  52. MMMMAAAALLLLLLLLOOOOCCCC TTTTRRRRAAAACCCCIIIINNNNGGGG
  53.      The library provides for tracing of all calls to any of the entry points
  54.      listed above, as well as any of the errors listed below.  The trace is
  55.      normally captured using a WorkShop performance experiment.  It may be
  56.      written in ASCII to stderr by enabling the environment variable
  57.      MALLOC_TRACING, although this typically produces a great deal of output.
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. MMMMAAAALLLLLLLLOOOOCCCC____CCCCVVVV((((3333))))                                                      MMMMAAAALLLLLLLLOOOOCCCC____CCCCVVVV((((3333))))
  71.  
  72.  
  73.  
  74. EEEERRRRRRRROOOORRRR DDDDEEEETTTTEEEECCCCTTTTIIIIOOOONNNN
  75.      The library will detect some errors under all conditions, and others if
  76.      MALLOC_FASTCHK error detection is enabled.  All errors pass through the
  77.      routine _c_v_m_a_l_l_o_c__e_r_r_o_r and a trap can be placed at the exit from that
  78.      routine to catch the problem.  Errors are also traced.
  79.  
  80.      The errors that are always detected are:
  81.           _m_a_l_l_o_c call failing (returning NULL).
  82.           _r_e_a_l_l_o_c call failing (returning NULL).
  83.           _r_e_a_l_l_o_c call with an address outside the range of heap addresses
  84.           returned by _m_a_l_l_o_c or _m_e_m_a_l_i_g_n.
  85.           _m_e_m_a_l_i_g_n call with an improper alignment.
  86.           _f_r_e_e call with an address that is improperly aligned.
  87.           _f_r_e_e call with an address outside the range of heap addresses
  88.           returned by _m_a_l_l_o_c or _m_e_m_a_l_i_g_n.
  89.  
  90.      If MALLOC_FASTCHK is enabled, the library will also detect:
  91.           _f_r_e_e or _r_e_a_l_l_o_c calls where the words prior to the user block have
  92.           been corrupted.
  93.           _f_r_e_e or _r_e_a_l_l_o_c calls where the words following the user block have
  94.           been corrupted.
  95.           _f_r_e_e or _r_e_a_l_l_o_c calls where the address is that of a block that has
  96.           already been freed.  This error may not always be detected if the
  97.           area around the block is reallocated after it was first freed.
  98.  
  99.      The behavior of the library is governed by various environment variables:
  100.  
  101.      MMMMAAAALLLLLLLLOOOOCCCC____VVVVEEEERRRRBBBBOOOOSSSSEEEE nnnn
  102.           (where n is an integer) controls printing of messages from the
  103.           library.  If n = 0, messages are printed to stderr ony when an error
  104.           occurs.  If n = 1 (the default), a messages is printed during
  105.           initialization, so that the user can tell that the library was
  106.           properly included in the application.  If n = 2 or greater, detailed
  107.           information about all traced events, including the callstack at the
  108.           time the error was detected, is printed.  This option is not
  109.           normally used by the end user, as it can produce a huge vloume of
  110.           output.
  111.  
  112.      MMMMAAAALLLLLLLLOOOOCCCC____TTTTRRRRAAAACCCCIIIINNNNGGGG
  113.           enables tracing of all calls through the library.  Tracing is
  114.           normally done in the course of a performance experiment; the
  115.           variable need not be set in such cases, as the running of the
  116.           experiment will automatically enable it.  If the option is enabled
  117.           when the program is run independently, and MALLOC_VERBOSE is set to
  118.           2 or greater, the trace events and program call stacks will be
  119.           written to stderr.
  120.  
  121.      MMMMAAAALLLLLLLLOOOOCCCC____FFFFAAAASSSSTTTTCCCCHHHHKKKK
  122.           enables corruption detection for library calls.  Corruption
  123.           detection is done by allocating a space larger than the requested
  124.           area, and putting specific patterns in front of and behind the area
  125.           returned to the caller.  When _f_r_e_e is called, the patterns are
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. MMMMAAAALLLLLLLLOOOOCCCC____CCCCVVVV((((3333))))                                                      MMMMAAAALLLLLLLLOOOOCCCC____CCCCVVVV((((3333))))
  137.  
  138.  
  139.  
  140.           checked, and if the area was overwritten, an error message is
  141.           printed using an internal call to the routine _c_v_m_a_l_l_o_c__e_r_r_o_r. Under
  142.           the debugger, a trap may be set at exit from this routine to catch
  143.           the program at the error.
  144.  
  145.      MMMMAAAALLLLLLLLOOOOCCCC____FFFFUUUULLLLLLLLWWWWAAAARRRRNNNN
  146.           enables detection of some calls that are not strictly errors, but
  147.           represent sloppy programming, including _f_r_e_e(NULL), _m_a_l_l_o_c(0), and
  148.           _r_e_a_l_l_o_c(ptr,0).
  149.  
  150.      MMMMAAAALLLLLLLLOOOOCCCC____MMMMAAAAXXXXMMMMAAAALLLLLLLLOOOOCCCC nnnn
  151.           (where n is an integer, in any base) sets a maximum size for any
  152.           _m_a_l_l_o_c or _r_e_a_l_l_o_c or _m_e_m_a_l_i_g_n allocation.  Any request exceeding
  153.           that size will be flagged as an error, and return a NULL pointer.
  154.  
  155.      MMMMAAAALLLLLLLLOOOOCCCC____NNNNOOOO____RRRREEEEUUUUSSSSEEEE
  156.           specifies that no area that has been freed will be reused.  With
  157.           this option enabled, no actual _f_r_e_e calls are really made, and the
  158.           process space and swap requirements can grow quite large.  If
  159.           MALLOC_FASTCHK is not enabled, any space that is freed by a realloc
  160.           may or may not get reused; if MALLOC_FASTCHK is enabled, such space
  161.           will not be reused.
  162.  
  163.      MMMMAAAALLLLLLLLOOOOCCCC____CCCCLLLLEEEEAAAARRRR____FFFFRRRREEEEEEEE
  164.           will clear the data upon any free call.  It will only work if
  165.           MALLOC_FASTCHK is also enabled.
  166.  
  167.      MMMMAAAALLLLLLLLOOOOCCCC____CCCCLLLLEEEEAAAARRRR____FFFFRRRREEEEEEEE____PPPPAAAATTTTTTTTEEEERRRRNNNN <<<<ppppaaaatttttttteeeerrrrnnnn>>>>
  168.           specifies a pattern to clear the data if MALLOC_CLEAR_FREE is
  169.           enabled.  The default pattern is 0xcafebeef for the 32-bit version,
  170.           and 0xcafebeefcafebeef for the 64-bit versions.  Only full words
  171.           (double words for 64-bits) are cleared to the pattern.
  172.  
  173.      MMMMAAAALLLLLLLLOOOOCCCC____CCCCLLLLEEEEAAAARRRR____MMMMAAAALLLLLLLLOOOOCCCC
  174.           will clear the memory area upon each allocation.  It also requires
  175.           MALLOC_FASTCHK be enabled.
  176.  
  177.      MMMMAAAALLLLLLLLOOOOCCCC____CCCCLLLLEEEEAAAARRRR____MMMMAAAALLLLLLLLOOOOCCCC____PPPPAAAATTTTTTTTEEEERRRRNNNN <<<<ppppaaaatttttttteeeerrrrnnnn>>>>
  178.           specifies a pattern to clear the data if MALLOC_CLEAR_MALLOC is
  179.           enabled.  The default pattern is 0xfacebeef for the 32-bit version,
  180.           and 0xfacebeeffacebeef for the 64-bit versions.  Only full words
  181.           (double words for 64-bits) are cleared to the pattern.
  182.  
  183. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  184.      malloc(3C), malloc(3X), cvspeed(1), cvperf(1).
  185.  
  186. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  187.      As ouput from the library routines.
  189.  
  190.  
  192.  
  193.  
  194.                                                                         PPPPaaaaggggeeee 3333
  195.  
  196.  
  197.  
  198.